home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Dr. Windows 3
/
dr win3.zip
/
dr win3
/
WINPROGS
/
WPJV1N7.ZIP
/
RTFGEN.ZIP
/
RTFGEN.DOC
< prev
next >
Wrap
Text File
|
1992-02-23
|
17KB
|
595 lines
February 22, 1992
RTFGEN
An ASCII to Rich Text Format Conversion Program
Version 1.0
OVERVIEW
Normally, to create a help file with the Windows help compiler,
you must first write a help topic file using a Rich Text Format
(RTF) word processor. For many, there are two problems here:
1. RTF word processors are expensive.
2. Learning to use a new word processor is a nuisance and not
very productive.
RTFGEN solves both these problems by allowing you to use your
favorite ASCII text editor to produce RTF formatted files
acceptable to the help compiler.
STEPS FOR BUILDING A HELP FILE
The steps required to create a Windows help file using RTFGEN
are:
1. Using an ASCII editor, create one or more input text files.
The layout of the input files will be discussed later.
2. Use RTFGEN to convert these files to RTF files.
3. Create a Help Project File (.HPJ) for input to the help
compiler. This file should reference the RTF files.
4. Run the help compiler to make the help file.
Steps 3 and 4 are described in the help compiler documentation.
This documentation deals with the first two steps only.
Once the ASCII files have been written, RTFGEN is used to
convert them to suitable RTF format. The file, HEADING, is used
in constructing the RTF file and must be present on the default
drive. From the DOS prompt:
RTFGEN [Infile [Outfile]]
The optional filenames specify the names of the ASCII input file
and the RTF file to be generated. If no extensions are given,
.RTF is used by default for the output file. If the output
filename is missing from the command line, an RTF file will be
created using the same name as the source file. When neither
filename is specified, names will be requested once execution
starts.
1
RTFGEN MYHELP
will cause RTFGEN to look for a source file, MYHELP, and create
an object file, MYHELP.RTF.
GENERAL EDITING CONSIDERATIONS
Almost any ASCII editor may be used. I use Borland's TURBO or
TPW. It's probably best to turn off options like 'optimal fill'
which can leave invisible and possibly unknown tab characters in
the document.
The use of tabs is required to obtain column allignment with
proportional fonts. Either the tab character or the RTF command,
\tab, may be used with the same effect.
Here are the default conditions use by RTFGEN:
Helv, 10 point font.
Paragraphs are left justified. The first line is not
indented.
Paragraph indentation is set by indentation of the first
line of the paragraph.
Tabs are spaced every 720 twips (about 6 default
characters).
Any of these defaults may be changed globally for the whole
document or locally at the topic, paragraph, or even character
level.
RTFGEN and/or the RTF language have special use for the following
characters:
` (grave accent) Used to mark end of paragraphs.
[,] Used to mark jumps and definitions.
{,} Used to mark areas where font characteristics will change.
\ Used as a command start character.
When these characters are to be used in the text, they should be
preceded by a '\'. Thus, '\[' will cause the left bracket to be
inserted in text and '\\' will result in a single backslash being
inserted in text.
(*...*) may be used to insert comments within the text.
2
ASCII INPUT FILE LAYOUT
The input file for RTFGEN should have the following sections:
1. An optional document header.
2. The command, \docstart, to mark the start of the document.
3. One or more topics consisting of:
a. A topic header.
b. A row of 5 or more '='s marking the start of the topic
text.
c. The topic text. This is basically the text to be
displayed in the help file.
d. A row of 5 or more '-'s marking the end of the topic.
4. The command, \docend, marking the end of the document.
Document Header
The optional document header may contain commands which will be
interpreted globally throughout the document. Commands
changing the font, font size, or first line indent might be
appropriate here.
The \docstart command follows the document header to mark the
start of the topics.
Example:
\f0 \fs24 (*Times Roman font, 12 pitch for entire file*)
\docstart
Topic Header
The topic header contains commands defining build tags, context
strings, title, keywords, and browse sequence number as
appropriate for the topic. Topic global formatting commands
may also be included. The topic header section is terminated
with a row of 5 or more '='s.
Example:
\title Table of Contents`
\topic contents`
\keyword contents`
\f0 \fs24 (* Times Roman font, 12 pitch for this topic *)
============ (* end of topic header *)
Topic Text
Text for the topic is entered here. Rules for text entry are:
Paragraph ends are marked with a grave accent, '`'
3
Blank lines will appear as blank lines.
By default, paragraphs are left justified. The indenting of
the paragraph is set by the indenting of the first line of
the paragraph. Indenting of lines after the first is
ignored.
Carriage returns and linefeeds within the paragraph are
ignored as far as the final results are concerned.
Commands may be interspersed within the text for special
effects. The commands themselves won't appear in the final
result.
Examples:
| Here is a typical paragraph. It will appear in the font
| and pitch specified in the topic header or document
| header. It is left justified and indented by 360 twips
| because the first line is so indented. The paragraph
| is terminated with a grave accent character.`
| \b\fi480 Here is another paragraph. It will appear in
| bold font because of the \b command. It will also be
| be indented by 360 twips and left justified. The
| \fi480 will cause the first line of the paragraph
| to be indented an additional 480 twips.`
COMMAND SYNTAX
Commands for RTFGEN and RTF commands passed thru to the help
compiler have a similar syntax. Commands start with a backslash
followed by a LOWERCASE alpha symbol. Some RTF commands
have a numerical value attached. Some RTFGEN commands have an
additional parameter string.
Examples:
\box
\topic <topic name>
\fs24 RTF command with number
\fi-720 '-' sign may be used if appropriate
When commands are mixed with t